home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / cug236.zip / BAWK.DOC < prev    next >
Text File  |  1980-01-02  |  11KB  |  320 lines
  1. /*
  2.     HEADER:        CUG000.00;
  3.     TITLE:        BAWK User Manual;
  4.     DATE:        05/17/1987;
  5.     VERSION:    1.1;
  6.     FILENAME:    BAWK.DOC;
  7.     SEE-ALSO:    BAWK.C;
  8.     AUTHORS:    B. Brodt;
  9. */
  10.  
  11.  
  12. NAME
  13.  
  14.     bawk - text processor
  15.  
  16. SYNOPSIS
  17.  
  18.     bawk rules [file] ...
  19.  
  20. DESCRIPTION
  21.  
  22.     Bawk is a text processing program that searches files for
  23.     specific patterns and performs "actions" for every occurrance
  24.     of these patterns.  The patterns can be "regular expressions"
  25.     as used in the UNIX "ex" editor.  The actions are expressed
  26.     using a subset of the "C" language.
  27.  
  28.     The patterns and actions are usually placed in a "rules" file
  29.     whose name must be the first argument in the command line.
  30.     All other arguments are taken to be the names of text files on
  31.     which the rules are to be applied.
  32.     The special file name "-" may also be used anywhere on the
  33.     command line to take input from the standard input device.
  34.  
  35.     The command:
  36.  
  37.         bawk - prog.c - prog.h
  38.  
  39.     would read the patterns and actions rules from the standard
  40.     input, then apply them to the files "prog.c", the standard
  41.     input and "prog.h" in that order.
  42.  
  43.     The general format of a rules file is:
  44.  
  45.         <pattern> { <action> }
  46.         <pattern> { <action> }
  47.         ...
  48.  
  49.     There may be any number of these <pattern> { <action> }
  50.     sequences in the rules file.  Bawk reads a line of input from
  51.     the current input file and applies every <pattern> { <action> }
  52.     in sequence to the line.
  53.     
  54.     If the <pattern> corresponding to any { <action> } is missing,
  55.     the action is applied to every line of input.  The default
  56.     { <action> } is to print the matched input line.
  57.  
  58. PATTERNS
  59.  
  60.     The <pattern>'s may consist of any valid C expression.  If the
  61.     <pattern> consists of two expressions seperated by a comma, it
  62.     is taken to be a range and the <action> is performed on all
  63.     lines of input that match the range.  <pattern>'s may contain
  64.     "regular expressions" delimited by an '@' symbol.  Regular
  65.     expressions can be thought of as a generalized "wildcard"
  66.     string matching mechanism, similar to that used by many
  67.     operating systems to specify file names.  Regular expressions
  68.     may contain any of the following characters:
  69.  
  70.         x    An ordinary character (not mentioned below)
  71.             matches that character.
  72.         '\'    The backslash quotes any character.
  73.             "\$" matches a dollar-sign.
  74.         '^'    A circumflex at the beginning of an expression
  75.             matches the beginning of a line.
  76.         '$'    A dollar-sign at the end of an expression
  77.             matches the end of a line.
  78.         '.'    A period matches any single character except
  79.             newline.
  80.         ':x'    A colon matches a class of characters described
  81.             by the character following it:
  82.         ':a'    ":a" matches any alphabetic;
  83.         ':d'    ":d" matches digits;
  84.         ':n'    ":n" matches alphanumerics;
  85.         ': '    ": " matches spaces, tabs, and other control
  86.             characters, such as newline.
  87.         '*'    An expression followed by an asterisk matches
  88.             zero or more occurrances of that expression:
  89.             "fo*" matches "f", "fo", "foo", "fooo", etc.
  90.         '+'    An expression followed by a plus sign matches
  91.             one or more occurrances of that expression:
  92.             "fo+" matches "fo", "foo", "fooo", etc.
  93.         '-'    An expression followed by a minus sign
  94.             optionally matches the expression.
  95.         '[]'    A string enclosed in square brackets matches
  96.             any single character in that string, but no
  97.             others.  If the first character in the string
  98.             is a circumflex, the expression matches any
  99.             character except newline and the characters in
  100.             the string.  For example, "[xyz]" matches "xx"
  101.             and "zyx", while "[^xyz]" matches "abc" but not
  102.             "axb".  A range of characters may be specified
  103.             by two characters separated by "-".  Note that,
  104.             [a-z] matches alphabetics, while [z-a] never
  105.             matches.
  106.  
  107.     For example, the following rules file would print every line
  108.     that contained a valid C identifier:
  109.  
  110.         @[a-zA-Z][a-zA-Z0-9]@
  111.  
  112.     And this rules file would print all lines between and including
  113.     the ones that contained the word "START" and "END":
  114.  
  115.         @START@, @END@
  116.  
  117. ACTIONS
  118.  
  119.     Actions are expressed as a subset of the C language.  All
  120.     variables are global and default to int's if not formally
  121.     declared.  Variable declarations may appear anywhere within
  122.     an action.  Only char's and int's and pointers and arrays of
  123.     char and int are allowed.  Bawk allows only decimal integer
  124.     constants to be used - no hex (0xnn) or octal (0nn). String
  125.     and character constants may contain all of the special C
  126.     escapes (\n, \r, etc.).
  127.  
  128.     Bawk supports the "if", "else", "while" and "break" flow of
  129.     control constructs, which behave exactly as in C.
  130.  
  131.     Also supported are the following unary and binary operators,
  132.     listed in order from highest to lowest precedence:
  133.  
  134.         operator           type    associativity
  135.         () []              unary   left to right
  136.         ! ~ ++ -- - * &    unary   right to left
  137.         * / %              binary  left to right
  138.         + -                binary  left to right
  139.         << >>              binary  left to right
  140.         < <= > >=          binary  left to right
  141.         == !=              binary  left to right
  142.         &                  binary  left to right
  143.         ^                  binary  left to right
  144.         |                  binary  left to right
  145.         &&                 binary  left to right
  146.         ||                 binary  left to right
  147.         =                  binary  right to left
  148.  
  149.     Comments are introduced by a '#' symbol and are terminated by
  150.     the first newline character.  The standard "/*" and "*/"
  151.     comment delimiters are not supported and will result in a
  152.     syntax error.
  153.  
  154. FIELDS
  155.  
  156.     When bawk reads a line from the current input file, the
  157.     record is automatically seperated into "fields".  A field is
  158.     simply a string of consecutive characters delimited by either
  159.     the beginning or end of line, or a "field seperator" character
  160.     Initially, the field seperators are the space and tab character.
  161.     The special unary operator '$' is used to reference one of the
  162.     fields in the current input record (line).  The fields are
  163.     numbered sequentially starting at 1.  The expression "$0"
  164.     references the entire input line.
  165.  
  166.     Similarly, the "record seperator" is used to determine the end
  167.     of an input "line", initially the newline character.
  168.     The field and record seperators may be changed programatically
  169.     by one of the actions and will remain in effect until changed
  170.     again.
  171.  
  172.     Fields behave exactly like strings; and can be used in the same
  173.     context as a character array.  These "arrays" can be considered
  174.     to have been declared as:
  175.  
  176.         char ($n)[ 128 ];
  177.  
  178.     In other words, they are 128 bytes long.  Notice that the
  179.     parentheses are necessary because the operators [] and $
  180.     associate from right to left; without them, the statement
  181.     would have parsed as:
  182.  
  183.         char $(1[ 128 ]);
  184.  
  185.     which is obviously ridiculous.
  186.  
  187.     If the contents of one of these field arrays is altered, the
  188.     "$0" field will reflect this change.  For example, this
  189.     expression:
  190.  
  191.         *$4 = 'A';
  192.  
  193.     will change the first character of the fourth field to an upper-
  194.     case letter 'A'.  Then, when the following input line:
  195.  
  196.         120 PRINT "Name         address        Zip"
  197.  
  198.     is processed, it would be printed as:
  199.  
  200.         120 PRINT "Name         Address        Zip"
  201.  
  202.     Fields may also be modified with the strcpy() function (see
  203.     below).  For example, the expression:
  204.  
  205.         strcpy( $4, "Addr." );
  206.  
  207.     applied to the same line above would yield:
  208.  
  209.         120 PRINT "Name         Addr.        Zip"
  210.  
  211. PREDEFINED VARIABLES
  212.  
  213.     The following variables are pre-defined:
  214.  
  215.         FS        Field seperator (see below).
  216.         RS        Record seperator (see below also).
  217.         NF        Number of fields in current input
  218.                 record (line).
  219.         NR        Number of records processed thus far.
  220.         FILENAME    Name of current input file.
  221.         BEGIN        A special <pattern> that matches the
  222.                 beginning of input text, before the
  223.                 first record is read.
  224.         END        A special <pattern> that matches the
  225.                 end of input text, after the last
  226.                 record has been read.
  227.  
  228.     Bawk also provides some useful builtin functions for string
  229.     manipulation and printing:
  230.  
  231.         printf(arg..)    Exactly the printf() function from C.
  232.         getline()    Reads the next record from the current
  233.                 input file and returns 0 on end of file.
  234.